██████╗ ███████╗████████╗██╗██████╗ ███████╗██████╗ ██╗ █████╗
██╔══██╗██╔════╝╚══██╔══╝██║██╔══██╗██╔════╝██╔══██╗██║██╔══██╗
██████╔╝█████╗ ██║ ██║██████╔╝█████╗ ██║ ██║██║███████║
██╔══██╗██╔══╝ ██║ ██║██╔═══╝ ██╔══╝ ██║ ██║██║██╔══██║
██║ ██║███████╗ ██║ ██║██║ ███████╗██████╔╝██║██║ ██║
╚═╝ ╚═╝╚══════╝ ╚═╝ ╚═╝╚═╝ ╚══════╝╚═════╝ ╚═╝╚═╝ ╚═╝
- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b- `b
¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯
Doxygen
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
top
mwbqDoxygen è una mwbgapplicazione per la generazione automatica della mwbwdocumentazione a partire dal mwcacodice sorgente di un generico mwcqsoftware. È un progetto mwcgopen source disponibile sotto mwcwlicenza GPL, scritto per la maggior parte da Dimitri van Heesch a partire dal mwda1997.
Doxygen è un sistema mwdgmultipiattaforma (mwdwWindows, mweaMac OS, mweqLinux, ecc.) ed opera con i mweglinguaggi mwewC++, mwfaC, mwfqJava, mwfgObjective C, mwfwPython, mwgaIDL (versioni mwgqCORBA e mwggMicrosoft), mwgwFortran, mwhaPHP, mwhqC#, e mwhgD. Nell'ambito del C++, è compatibile con le estensioni mwhwQt.
Il sistema estrae la documentazione dai mwjqcommenti inseriti nel codice sorgente e dalla dichiarazione delle mwjgstrutture dati.
Contents
• Utilizzo
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
La documentazione prodotta
Il risultato finale è disponibile sotto forma di pagine mwlaHTML oppure nei formati mwlqCHM, mwlgRTF, mwlwPDF, mwmaLaTeX, mwmqPostScript o mwmgman pages di mwmwUnix. Il formato HTML prodotto si giova di un sistema di mwnahyperlink molto curato che permette al lettore un'agevole navigazione della struttura dei mwnqfile sorgenti. La documentazione prodotta riporta anche il mwngdiagramma delle classi, nei casi in cui sono presenti relazioni di mwnwereditarietà tra strutture dati. Grazie all'impiego sinergico di Doxygen con mwoaGraphviz, è possibile includere nella documentazione diagrammi delle classi per tutti gli altri tipi di relazioni tra strutture dati. I documenti possono essere generati in diverse lingue, tra cui è compreso l'italiano.
Infine, il sistema è altamente e facilmente configurabile al fine di permettere all'utilizzatore di intervenire su tutti gli aspetti della documentazione prodotta.
Il formato dei commenti
Il funzionamento di Doxygen richiede una particolare formattazione dei commenti inseriti nel codice sorgente. Le regole di formattazione, oltre ad essere analoghe a quelle degli altri prodotti della categoria, sono chiaramente documentate nel manuale. Riportiamo di seguito un esempio.
/**
* The time class represents a moment of time.
*
* \author My Name
*/
class Time {
/**
* Constructor that sets the time to a given value.
* \param timemillis Number of milliseconds passed since Jan 1. 1970
*/
Time(int timemillis) {
...
}
/**
* Get the current time.
* \return A time object set to the current time.
*/
static Time now() {
...
}
};
Il file di configurazione
Doxygen associa ad ogni progetto da documentare un mwcafile di configurazione che contiene le impostazioni da utilizzare per la generazione. Questo file è un elenco di assegnazioni di opportuni valori a determinati parametri (mwcqTAG). Ogni tag è formato dalla coppia di informazioni
mwcwNOME_PARAMETRO = VALORE_PARAMETRO
analogamente a quanto avviene nei file di configurazione di numerosi altri prodotti open source. Un frammento di un esempio del file di configurazione è il seguente:
# The PROJECT_NAME tag is a single word (or a sequence of words surrounded
# by quotes) that should identify the project.
PROJECT_NAME = MyProject
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute)
# base path where the generated documentation will be put.
# If a relative path is entered, it will be relative to the location
# where doxygen was started. If left blank the current directory will be used.
OUTPUT_DIRECTORY =
# The OUTPUT_LANGUAGE tag is used to specify the language in which all
# documentation generated by doxygen is written.
OUTPUT_LANGUAGE = English
# The INPUT tag can be used to specify the files and/or directories that contain
# documented source files. You may enter file names like "myfile.cpp"
# or directories like "/usr/src/myproject".
# Separate the files or directories with spaces.
INPUT =
# If the value of the INPUT tag contains directories, you can use the
# FILE_PATTERNS tag to specify one or more wildcard pattern (like *.cpp
# and *.h) to filter out the source-files in the directories. If left
# blank the following patterns are tested:
# *.c *.cc *.cxx *.cpp *.c++ *.java *.ii *.ixx *.ipp *.i++ *.inl *.h *.hh *.hxx *.hpp
# *.h++ *.idl *.odl *.cs *.php *.php3 *.inc *.m *.mm
FILE_PATTERNS = *.h *.hh *.idl
# The RECURSIVE tag can be used to turn specify whether or not subdirectories
# should be searched for input files as well. Possible values are YES and NO.
# If left blank NO is used.
RECURSIVE = YES
# If the GENERATE_HTML tag is set to YES (the default) Doxygen will
# generate HTML output.
GENERATE_HTML = YES
# The HTML_OUTPUT tag is used to specify where the HTML docs will be put.
# If a relative path is entered the value of OUTPUT_DIRECTORY will be
# put in front of it. If left blank -html- will be used as the default path.
HTML_OUTPUT = html
# If the GENERATE_LATEX tag is set to YES (the default) Doxygen will
# generate Latex output.
GENERATE_LATEX = NO
# The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put.
# If a relative path is entered the value of OUTPUT_DIRECTORY will be
# put in front of it. If left blank -latex- will be used as the default path.
LATEX_OUTPUT = latex
Come si vede, attraverso il file di configurazione, l'utente stabilisce:
• Il nome del progetto
• la mwxadirectory dove verrà generato il materiale (mwxqdirectory di destinazione)
• la lingua della documentazione prodotta
• la directory dove si trovano i file sorgente da documentare (mwyadirectory di origine)
• l'estensione dei file di input da considerare come origine
• l'indicazione di ricorsività nella directory di origine
• l'indicazione di generazione del formato HTML
• nome della directory di destinazione per il formato HTML
• l'indicazione di generazione del formato LaTeX
• nome della directory di destinazione per il formato LaTeX
Doxygen è in grado di generare un file di configurazione generico con il comando
mw0q doxygen -g <config-file>
il file generato automaticamente da doxygen contiene dei parametri generici che l'utente può personalizzare o lasciare invariati.
Utilizzo
Dopo aver installato Doxygen ed aver generato ed eventualmente modificato il file di configurazione, si può invocare l'esecuzione di Doxygen con il comando
mw1gdoxygen <config-file>
al termine della elaborazione, il materiale prodotto sarà disponibile nella directory di destinazione indicata nel file di configurazione.
Altri progetti
Altri progetti
• Wikimedia Commons
• Wikimedia Commons contiene immagini o altri file su Doxygen
Collegamenti esterni
• (EN) Sito ufficiale, su doxygen.org.
• citerefsourceforge(EN) Doxygen, su SourceForge.
• Doxygen, su packages.debian.org.
• citerefgithub(EN) Doxygen, su GitHub.
• Repository sorgenti di Doxygen, su github.com.
• citereffree-software-directory(EN) Doxygen, su Free Software Directory.
• mw3g(EN) 10 Minuti per documentare il codice, su codeproject.com.